/* Copyright(C) 2006-2008 Dave Sexton  *
 * http://www.codeplex.com/aip         *
 * http://www.codeplex.com/aip/license *
 ***************************************/
using System;
using System.Collections.Generic;
using System.Text;
using System.Drawing;
using System.Configuration.Provider;
using DaveSexton.Web.Controls.Resources;

namespace DaveSexton.Web.Controls
{
	/// <summary>
	/// An implementation of <see cref="AutoInputProtectionTextProvider"/> that generates random English words from the 
	/// Ogden dictionary.  This class cannot be inherited.
	/// </summary>
	/// <remarks>
	/// <para>
	/// <see cref="BasicEnglishAutoInputProtectionTextProvider"/> is the default text provider that is used when no 
	/// text providers are configured.
	/// </para>
	/// <para>
	/// See the remarks in the <see cref="GenerateRandomAutoInputProtectionText"/> method for more information.
	/// </para>
	/// </remarks>
	/// <include file='examples.xml' path='//example[@id="BasicEnglish"][@type="images"]'/>
	/// <include file='examples.xml' path='//example[@id="BasicEnglish"][@type="config"]'/>
	/// <seealso cref="AutoInputProtection.DefaultTextProvider"/>
	/// <seealso cref="Configuration.AutoInputProtectionSection"/>
	/// <seealso cref="AutoInputProtectionImageProvider"/>
	/// <seealso cref="AutoInputProtectionFilterProvider"/>
	public sealed class BasicEnglishAutoInputProtectionTextProvider : AutoInputProtectionTextProvider
	{
		#region Constructors
		/// <summary>
		/// Constructs a new instance of the <see cref="BasicEnglishAutoInputProtectionTextProvider" /> class.
		/// </summary>
		public BasicEnglishAutoInputProtectionTextProvider()
		{
		}

		/// <summary>
		/// Constructs a new instance of the <see cref="BasicEnglishAutoInputProtectionTextProvider" /> class.
		/// </summary>
		/// <param name="colors">An <see cref="IEnumerable{T}"/> of <see cref="Color">Colors</see> from which an 
		/// <see cref="AutoInputProtectionImage"/> implementation may sample at random.</param>
		/// <param name="fonts">An <see cref="IEnumerable{T}"/> of <see cref="Font">Fonts</see> from which an 
		/// <see cref="AutoInputProtectionImage"/> implementation may sample at random.</param>
		public BasicEnglishAutoInputProtectionTextProvider(IEnumerable<Color> colors, IEnumerable<Font> fonts)
			: base(colors, fonts)
		{
		}
		#endregion

		#region Methods
		/// <summary>
		/// Loads the provider's settings from the specified <paramref name="config"/>.
		/// </summary>
		/// <exception cref="ProviderException">Either no colors or no fonts are configured, a font name is invalid, an attribute
		/// value cannot be converted into the required type, the maximumCharacters value is not a positive integer or it is less than 
		/// minimumCharacters, or the minimumCharacters value is not a positive integer.</exception>
		/// <param name="name">Name of the provider.</param>
		/// <param name="config">A collection of name and value pairs that will be used to initialize the provider.</param>
		public override void Initialize(string name, System.Collections.Specialized.NameValueCollection config)
		{
			if (config == null)
				throw new ArgumentNullException("config");

			if (String.IsNullOrEmpty(name))
				name = "BasicEnglishAutoInputProtectionTextProvider";

			if (string.IsNullOrEmpty(config["description"]))
			{
				config.Remove("description");
				config.Add("description", "Basic English Auto-Input Protection Text Provider");
			}

			base.Initialize(name, config);

			// Throw an exception if unrecognized attributes remain
			if (config.Count > 0)
			{
				string attr = config.GetKey(0);

				if (!String.IsNullOrEmpty(attr))
					throw new ProviderException(string.Format(System.Globalization.CultureInfo.CurrentUICulture, 
						Errors.UnrecognizedAttribute, attr));
			}
		}

		/// <summary>
		/// Returns a random basic English word from the Ogden dictionary to be used as the text on an image that is generated by an 
		/// <see cref="AutoInputProtectionImage"/> implementation.
		/// </summary>
		/// <remarks>
		/// <see cref="RandomString.CreateBasicEnglishWord"/> is used to get a word at random from the Ogden Basic English dictionary, 
		/// which is stored as an embedded resource in the AIP class library.  The number of letters in the chosen word will be no less than 
		/// <see cref="AutoInputProtectionTextProvider.MinimumCharacters"/> and no more than <see cref="AutoInputProtectionTextProvider.MaximumCharacters"/>.
		/// </remarks>
		/// <returns>A random basic English word from the Ogden dictionary that can be used on an image for user validation.</returns>
		public override string GenerateRandomAutoInputProtectionText()
		{
			return RandomString.CreateBasicEnglishWord(MinimumCharacters, MaximumCharacters);
		}
		#endregion
	}
}
